home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1999 March / EnigmA AMIGA RUN 35 (1999)(G.R. Edizioni)(IT)[!][issue 1999-03].iso / earcd / devel / vbcc-wos / vbccwos.readme
Text File  |  1999-01-01  |  14KB  |  503 lines
  1. Short:    Free optimizing ANSI C compiler (PPC/WarpOS)
  2. Uploader: volker@vb.franken.de (Volker Barthelmann)
  3. Author:   volker@vb.franken.de (Volker Barthelmann)
  4. Type:     dev/c
  5. Version:  0.7
  6. Replaces: dev/c/vbcc.lha
  7.  
  8. vbcc - portable ANSI C compiler (c) in 1995-99 by Volker Barthelmann
  9.  
  10.  
  11. INTRODUCTION
  12.  
  13.     vbcc is a free portable and retargetable ANSI C compiler.
  14.  
  15.     This archive contains the compiler, preprocessor, assembler, linker,
  16.     frontend, message browser, startup codes, C-libraries, amiga.lib
  17.     replacements as well as several other tools for PPC/WarpOS.
  18.  
  19.     This gives you a complete system that allows to develop programs in
  20.     ANSI C as well as Amiga-specific programs (provided you obtain the
  21.     OS-includes) running on PPC/WarpOS.
  22.  
  23.     All major parts of this distribution (including compiler, preprocessor,
  24.     libraries etc.) have been compiled/assembled with this system and
  25.     apart from the OS-includes everything needed to rebuild vbcc,
  26.     the libraries and many of the other programs is contained in this
  27.     archive and the corresponding source archive.
  28.  
  29.     Note that the programs in this archive all run on the 68k. There is
  30.     another archive which contains compilers that run native under WarpOS.
  31.  
  32.  
  33. FEATURES
  34.  
  35.     vbcc..
  36.  
  37.     - comes with source
  38.  
  39.     - is free
  40.  
  41.     - is portable and retargetable
  42.  
  43.     - comes with a global optimizer that can e.g. do global common
  44.       subexpression elimination, constant propagation, function inlining
  45.       and several other optimizations (but is not yet finished and may
  46.       have some bugs)
  47.  
  48.     - should be ANSI compliant
  49.  
  50.     - can generate code that runs on a plain 68000 CPU
  51.  
  52.     - can generate code optimized for 020/030, 040 or 060
  53.  
  54.     - can generate code that uses the 68881/2, 68040/060 FPUs directly
  55.       and comes with appropriate math-libraries
  56.  
  57.     - can generate code that runs on PowerUp-boards
  58.  
  59.     - generates standard Amiga-68k-objects, PPC-ELF-objects or
  60.       WarpOS-EHF-objects
  61.  
  62.     - does not need too much memory
  63.  
  64.     - comes with a message browser
  65.  
  66.     - comes with a config program
  67.  
  68.     - offers a lot of error/warning messages that can be turned on/off
  69.       separately
  70.  
  71.  
  72. WHAT'S NEW
  73.  
  74.     Some changes since the last release:
  75.  
  76.     - bug fixes
  77.  
  78.     - new optimizations
  79.  
  80.     - much improved libaries
  81.  
  82.     - use of Frank Wille's linker vlink
  83.  
  84.     - support for PPC/WarpOS
  85.  
  86.     - support for small data for PPC/ELF
  87.  
  88.     - support for __saveds (68k, PPC/ELF and PPC/WarpOS)
  89.  
  90.     - support for __far (68k, PPC/EFL and PPC/WarpOS)
  91.  
  92.     - support for __chip (68k and PPC/WarpOS)
  93.  
  94.     - support for auto opening of libraries (68k, PPC/ELF and PPC/WarpOS)
  95.  
  96.     - cleaned up distributions for all three Amiga targets
  97.  
  98.     - checking for unresolved symbols for PPC/ELF
  99.  
  100.     - scheduler for PPC (ELF and WarpOS)
  101.  
  102.  
  103. REQUIREMENTS
  104.  
  105.     To use vbcc you need:
  106.  
  107.     - an Amiga with OS 2.0 or higher
  108.  
  109.     - enough RAM (it is possible to translate small programs with 1MB, but
  110.       for larger programs much more will be needed)
  111.  
  112.     Stuff that is not needed, but may be very useful:
  113.  
  114.     - harddisk
  115.  
  116.     - editor
  117.  
  118.     - make, touch etc.
  119.  
  120.     - the Amiga OS-includes (they can be found on certain CDs)
  121.  
  122.     - pipe-command (to use the message browser)
  123.  
  124.     Also you should know how to use the shell and you should know ANSI C
  125.     (if you need a book I recommend (like everyone) "The C Programming
  126.     Language, Second Edition, ANSI C" by Kernighan and Ritchie).
  127.  
  128.  
  129. LEGAL
  130.  
  131.     Note that this distribution contains several programs, libraries etc.
  132.     that are from different authors and are under different legal status.
  133.     So always read the corresponding doc/guide-file to find out under
  134.     what conditions a certain file may be used, distributed etc.
  135.  
  136.     For the most part you can assume that you may use everything for
  137.     non-commercial purposes and may distribute the unchanged archive
  138.     in whole.
  139.  
  140.     Changing any parts from this archive, distributing parts of it or
  141.     using it commercially might be legal for certain parts, but illegal
  142.     for others, so read all docs carefully before doing any of the above.
  143.  
  144.     This archive contains code written by (this list may be incomplete):
  145.  
  146.     Volker Barthelmann, Frank Wille, Thorsten Schaaps, Dennis Ritchie,
  147.     Matthias Fleischer, Gunther Nikl, Mike Schwartz, Kasper Graversen,
  148.     Johnny Tevessen, Andreas Heumann
  149.  
  150.     However, if you have any comments/problems etc. with anything, please
  151.     do not bother them, but write to me (volker@vb.franken.de) first.
  152.     Exceptions are the parts by Kasper Graversen and the WarpOS support
  153.     by Frank Wille.
  154.  
  155.  
  156. INSTALLATION/TUTORIAL
  157.  
  158.     [Names of directories, binaries or assigns have changed since earlier
  159.      versions as have config-files. So users of earlier versions should
  160.      read this again and do a complete re-install to avoid problems.]
  161.  
  162.     The first step (which you probably already did) is to extract the
  163.     entire archive (take care to preserve the file attributes). If you
  164.     have several archives of the vbcc distribution you can just extract
  165.     them all to the same place.
  166.  
  167.     The distributed programs are for the most part only usable from a shell.
  168.  
  169.     To use vbcc the following steps are necessary:
  170.  
  171.     1. Go to the subdirectory vbcc/machines/amiga.
  172.  
  173.     2. If you have the Amiga OS-includes copy them into the include
  174.        directory.
  175.  
  176.     3. Execute the script init_vbcc.
  177.  
  178.     4. If you compile larger projects it may be necessary to increase
  179.        the stack further.
  180.  
  181.     If you use vbcc frequently it is probably a good idea to add those
  182.     commands to your user-startup, shell-startup or similar.
  183.  
  184.     Now you should be able to use vbcc. E.g. if you want to compile and
  185.     link the program hello.c you can type
  186.  
  187.         vc +warpos hello.c
  188.  
  189.     This will compile and link the file hello.c and create the executable
  190.     a.out in the current directory.
  191.  
  192.         vc +warpos hello.c -o hello
  193.  
  194.     will do the same, but the created executable will be called hello.
  195.  
  196.         vc +warpos -c t1.c t2.c
  197.  
  198.     will compile t1.c and t2.c without linking, creating the object files
  199.     t1.o and t2.o.
  200.  
  201.         vc +warpos t1.o t2.o -o tt
  202.  
  203.     will link them together and create the executable tt.
  204.  
  205.     If your program uses floating point add -lm to the commandline
  206.     to link with the math-library, e.g.:
  207.  
  208.         vc +warpos calc.c -o calc -lm
  209.  
  210.     This distribution also contains a port of Motorola's fast libmoto
  211.     math-library, done by Andreas Heumann. If you want to use it, link
  212.     with -lppcmath before -lm, e.g.:
  213.  
  214.         vc +warpos calc.c -o calc -lppcmath -lm
  215.  
  216.     IMPORTANT: If your program uses AmigaOS-functions you have to specify
  217.     the option -amiga-align, e.g.
  218.  
  219.         vc +warpos -amiga-align myOsPrg.c
  220.  
  221.     There is also an extra.lib which includes a few functions that are
  222.     no standard ANSI functions but some people seem to regard them as
  223.     standard functions. If you use one of these add -lextra to the
  224.     commandline and read:
  225.  
  226.         vbcc/machines/amiga/doc/extralibwarpos.doc
  227.  
  228.     For further information read the files:
  229.  
  230.         vbcc/doc/vbcc.doc
  231.         vbcc/doc/vc.doc
  232.         vbcc/doc/vbccppc.doc
  233.         vbcc/machines/amiga/doc/vclibwos.doc
  234.  
  235.  
  236. SUPPORT FOR OTHER TARGETS
  237.  
  238.     This release of vbcc is able to generate code for 68k, PPC/ELF
  239.     and PPC/WarpOS. If you have installed other backends you can
  240.     choose the target by specifying another config file with the
  241.     '+'-option (e.g. +ppc).
  242.  
  243.     For further details see the corresponding docs for this target.
  244.  
  245.  
  246. CONFIGURATION
  247.  
  248.     The frontend searches for a file vc.config in ENV: and vbcc: to read
  249.     preferences. The provided sample vc.config should be usable and does
  250.     not have to be changed but you can add something to suit your personal
  251.     preferences - read
  252.  
  253.         vbcc/doc/vc.doc
  254.  
  255.     to find out more.
  256.  
  257.  
  258. MESSAGE BROWSER
  259.  
  260.     If you start the message browser with
  261.  
  262.         run vbrowse
  263.  
  264.     it will open a window with a listview gadget. If you have a pipe
  265.     command installed you can now invoke vc via tovbr, e.g.
  266.  
  267.         tovbr vc hello.c
  268.  
  269.     and any output from vc will be displayed in the window of vbrowse
  270.     rather than in the shell. It might be convenient to make an alias like
  271.  
  272.         alias vb tovbr vc
  273.  
  274.     so that invoking vb will automatically display the output in the browser.
  275.  
  276.     If there is an error/warning-message in the browser you can invoke a
  277.     configurable command by double-clicking on the message.
  278.  
  279.     Double-clicking on the quoted line will invoke GoldEd (if you have it
  280.     installed) by default, load the file that caused the error and the cursor
  281.     will be placed on this line in the default configuration. If you use
  282.     another editor or want to change this behaviour have a look at
  283.     vbcc/machines/amiga/doc/vbrowse.doc.
  284.  
  285.     Double-clicking on the error-line (the one below the quoted line) will
  286.     invoke the command showerr that will open the VBCCMessages.guide and
  287.     display a more detailed description of the error (if there is one in
  288.     the guide - there are not yet descriptions for all messages).
  289.  
  290.     Read vbcc/machines/amiga/vbrowse.doc for further information.
  291.  
  292.  
  293. CONTENTS
  294.  
  295.     This archive contains (among others) the following files and directories:
  296.  
  297.     vbcc/
  298.  
  299.             The main directory. The source files for the compiler and the
  300.             builtin preprocessor by Thorsten Schaaps are here.
  301.  
  302.     vbcc/doc/
  303.  
  304.             Host independant documentation for the compiler is in this dir.
  305.  
  306.     vbcc/doc/History
  307.  
  308.             Changes in since earlier versions of the compiler.
  309.  
  310.     vbcc/doc/vbcc.doc
  311.  
  312.             Documentation for the target-independant part of the compiler.
  313.  
  314.     vbcc/doc/vbcc.faq
  315.  
  316.             Frequently asked questions about vbcc.
  317.  
  318.     vbcc/doc/errors.doc
  319.  
  320.             A list of all error/warning-messages from the compiler -
  321.             sometimes with more detailed descriptions.
  322.  
  323.     vbcc/doc/vbccppc.doc
  324.  
  325.             Documentation for the PPC code generator.
  326.  
  327.     vbcc/doc/vc.doc
  328.  
  329.             Documentation for the compiler-frontend.
  330.  
  331.     vbcc/doc/pasm.doc
  332.  
  333.             Documentation for the assembler by Frank Wille.
  334.  
  335.     vbcc/doc/vlink.doc
  336.  
  337.             Documentation for the linker by Frank Wille.
  338.  
  339.     vbcc/doc/vcpp.doc
  340.  
  341.             Some short comments regarding the preprocessor from the
  342.             lcc-distribution. Read the copyright-notice.
  343.  
  344.     vbcc/doc/building.doc
  345.  
  346.             Documentation on building vbcc.
  347.  
  348.     vbcc/bin/
  349.  
  350.             The directory containing binaries of preprocessor, compiler and
  351.             frontend. Additional binaries may be in machines/xyz/bin/.
  352.  
  353.     vbcc/bin/vbccm68k
  354.  
  355.             The native C compiler for m68k.
  356.  
  357.     vbcc/bin/vbccppc
  358.  
  359.             The C cross-compiler for PPC. Running on m68k.
  360.  
  361.     vbcc/bin/vbccm68k_ppc
  362.  
  363.             The C cross-compiler for m68k. Running on PPC/ELF. (optional)
  364.  
  365.     vbcc/bin/vbccppc_ppc
  366.  
  367.             The native C compiler for PPC/ELF. (optional)
  368.  
  369.     vbcc/bin/vbccm68k_wos
  370.  
  371.             The C cross-compiler for m68k. Running on PPC/WOS. (optional)
  372.  
  373.     vbcc/bin/vbccppc_wos
  374.  
  375.             The native C compiler for PPC/WOS. (optional)
  376.  
  377.     vbcc/bin/vc
  378.  
  379.             The compiler-frontend.
  380.  
  381.     vbcc/bin/pasm
  382.  
  383.             The assembler by Frank Wille.
  384.  
  385.     vbcc/bin/vlink
  386.  
  387.             The linker by Frank Wille.
  388.  
  389.     vbcc/bin/vcpp
  390.  
  391.             The preprocessor from the lcc-distribution (by Dennis Ritchie).
  392.  
  393.     vbcc/machines/amiga/doc/
  394.  
  395.             This contains documentation for the Amiga specific parts.
  396.  
  397.     vbcc/machines/amiga/doc/extralibppc.doc
  398.  
  399.             Documentation for extra.lib.
  400.  
  401.     vbcc/machines/amiga/doc/VBCCMessages.guide
  402.  
  403.             The vbcc/doc/errors.doc in Amigaguide-format (done by Walter
  404.             Doerwald).
  405.  
  406.     vbcc/machines/amiga/doc/vclibwos.doc
  407.  
  408.             Documentation for the Amiga-C-library.
  409.  
  410.     vbcc/machines/amiga/doc/vbrowse.doc
  411.  
  412.             Documentation on the message browser and several connected tools.
  413.  
  414.     vbcc/machines/amiga/init_vbcc
  415.  
  416.             A sample script to do the necessary assigns etc. to use vbcc.
  417.  
  418.     vbcc/machines/amiga/include
  419.  
  420.             Here you can install the OS-includes.
  421.  
  422.     vbcc/machines/amiga/bin/
  423.  
  424.             This directory contains all Amiga-specific executables.
  425.  
  426.     vbcc/machines/amiga/bin/vbrowse
  427.     vbcc/machines/amiga/bin/vsend
  428.     vbcc/machines/amiga/bin/tovbr
  429.     vbcc/machines/amiga/bin/showerr
  430.  
  431.             The message browser and some tools.
  432.  
  433.     vbcc/machines/amigawos/include
  434.  
  435.             This directory contains the standard-ANSI-includes for vc.lib.
  436.  
  437.     vbcc/machines/amigawos/bin/
  438.  
  439.             This directory contains AmigaWOS-specific executables.
  440.  
  441.     vbcc/machines/amiga/bin/inlinetoolWOS
  442.  
  443.             Utility to generate inline headers for r2-based
  444.             WarpOS libraries.
  445.  
  446.     vbcc/machines/amiga/bin/fd2libWOS
  447.  
  448.             fd2lib generates stubs for shared libraries and must be used to
  449.             rebuilt amiga.lib or if you want to use any custom shared-library.
  450.  
  451.     vbcc/machines/amigawos/lib/
  452.  
  453.             This directory contains the link-libraries and startup-codes.
  454.  
  455.     vbcc/machines/amigawos/lib/warpup.o
  456.  
  457.             The standard startup-code for vc.lib.
  458.  
  459.     vbcc/machines/amigawos/lib/vc.lib
  460.  
  461.             The standard C-library.
  462.  
  463.     vbcc/machines/amigawos/lib/m.lib
  464.  
  465.             Math-library.
  466.  
  467.     vbcc/machines/amigawos/lib/ppcmath.lib
  468.  
  469.             Libmoto math-library for WarpOS by Andreas Heumann.
  470.  
  471.     vbcc/machines/amigawos/lib/amiga.lib
  472.  
  473.             Replacement for the standard amiga.lib.
  474.  
  475.     vbcc/machines/amigawos/lib/auto.lib
  476.  
  477.             Library for automatic opening of system libraries.
  478.  
  479.     vbcc/machines/amigawos/lib/extra.lib
  480.  
  481.             Very small library containing a few functions some people want.
  482.  
  483.  
  484.  
  485. BUGREPORTS/COMMENTS
  486.  
  487.     If you think vbcc generates bad code, throws enforcer hits, crashes,
  488.     seems to be not ANSI-compliant etc. and the problem is not mentioned
  489.     anywhere in this docs as known problem, please send a mail with your
  490.     system configuration, the vbcc version, the command line you used, the
  491.     source that caused the problem and a brief description of the problem to
  492.  
  493.         volker@vb.franken.de
  494.  
  495.     Also if you find problems with the includes, the libraries or you have
  496.     suggestions, dislikes etc. send me a mail.
  497.     Corrections, improvements etc. of the manuals are appreciated, too.
  498.  
  499.  
  500.  
  501. Volker Barthelmann                                      volker@vb.franken.de
  502.  
  503.